<!-------- @HEADER
 !
 ! !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
 !
 !  Zoltan Toolkit for Load-balancing, Partitioning, Ordering and Coloring
 !                  Copyright 2012 Sandia Corporation
 !
 ! Under the terms of Contract DE-AC04-94AL85000 with Sandia Corporation,
 ! the U.S. Government retains certain rights in this software.
 !
 ! Redistribution and use in source and binary forms, with or without
 ! modification, are permitted provided that the following conditions are
 ! met:
 !
 ! 1. Redistributions of source code must retain the above copyright
 ! notice, this list of conditions and the following disclaimer.
 !
 ! 2. Redistributions in binary form must reproduce the above copyright
 ! notice, this list of conditions and the following disclaimer in the
 ! documentation and/or other materials provided with the distribution.
 !
 ! 3. Neither the name of the Corporation nor the names of the
 ! contributors may be used to endorse or promote products derived from
 ! this software without specific prior written permission.
 !
 ! THIS SOFTWARE IS PROVIDED BY SANDIA CORPORATION "AS IS" AND ANY
 ! EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
 ! IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
 ! PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL SANDIA CORPORATION OR THE
 ! CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
 ! EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
 ! PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
 ! PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
 ! LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
 ! NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
 ! SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 !
 ! Questions? Contact Karen Devine	kddevin@sandia.gov
 !                    Erik Boman	egboman@sandia.gov
 !
 ! !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
 !
 ! @HEADER
-------> 

<!doctype html public "-//w3c//dtd html 4.0 transitional//en">
<html>
<head>
   <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
   <meta name="GENERATOR" content="Mozilla/4.7 [en] (X11; U; SunOS 5.7 sun4u) [Netscape]">
   <meta name="sandia.approved" content="SAND99-1376">
   <meta name="author" content="karen devine, kddevin@sandia.gov">
   <title> Zoltan Developer's Guide:  Parameter Setting Routines</title>
</head>
<body bgcolor="#FFFFFF">

<div ALIGN=right><b><i><a href="dev.html">Zoltan Developer's Guide</a>&nbsp; |&nbsp; <a href="dev_services_parallel.html">Next</a>&nbsp; |&nbsp; <a href="dev_services.html">Previous</a></i></b></div>
<!------------------------------------------------------------------------->


<h2>
<a NAME="Parameters"></a>Parameter Setting Routines</h2>
Zoltan allows applications to change a number of parameter settings at
runtime. This facility supports debugging by, for instance, allowing control
over the type and quantity of output. It also allows users to modify some
of the parameters that characterize the partitioning algorithms. The design
of the parameter setting routines was driven by several considerations.
First, we wanted to keep the user interface as simple as possible. Second,
we wanted to allow different Zoltan structures to have different
parameter settings associated with them. This second consideration precluded
the use of C's static global variables (except in a few special places).
The parameter routines described below allow developers to provide runtime
access to any appropriate variables. In some cases,
it is appropriate to allow developers to tinker with parameters that will
never be documented for users.
<p>Our solution to parameter setting is to have a single interface routine
<b><a href="#Zoltan_Set_Param">Zoltan_Set_Param</a></b>.
This function calls a set of more domain-specific parameter setting routines,
each of which is responsible for a domain-specific set of parameters. Assuming
there are no errors, the parameter name and new value are placed in a linked
list of new parameters which is maintained by the Zoltan structure.
When a partitioning method is invoked on a Zoltan structure, it
scans through this linked list using the <b><a href="#Zoltan_Assign_Param_Vals">Zoltan_Assign_Param_Vals</a></b>
function, resetting parameter values that are appropriate to the method.
<p>In addition to the method-specific parameters, Zoltan also has a set
of so-called&nbsp;<a NAME="key_params"></a><b>key parameters</b>. These
are normally stored in the Zoltan structure and may be accessed by
any part of the Zoltan code (including all the methods). A list of the
<a href="../ug_html/ug_param.html#General_Parameters">key
parameters currently used in Zoltan</a> can be found in the User's Guide.
<p>The routines that control parameter setting are listed below. Note that
these routines have been written to be as independent of Zoltan as possible.
Only a few minor changes would be required to use these routines as a separate
library.
<blockquote>
<b><a href="#Zoltan_Set_Param">Zoltan_Set_Param</a></b>:&nbsp; User
interface function that calls a set of method-specific routines.
<br><b><a href="#Zoltan_Set_Param_Vec">Zoltan_Set_Param_Vec</a></b>:&nbsp; 
Same as Zoltan_Set_Param, but for vector parameters. 
<br><b><a href="#Zoltan_Check_Param">Zoltan_Check_Param</a></b>:&nbsp; Routine
to check if parameter name and value are OK.
<br><b><a href="#Zoltan_Bind_Param">Zoltan_Bind_Param</a></b>: Routine to associate a parameter name with a variable.
<br><b><a href="#Zoltan_Bind_Param_Vec">Zoltan_Bind_Param_Vec</a></b>: Same as Zoltan_Bind_Param, but for vector parameters.
<br><b><a href="#Zoltan_Assign_Param_Vals">Zoltan_Assign_Param_Vals</a></b>:&nbsp;
Scans list of parameter names &amp; values, setting relevant parameters
accordingly.
<br><b><a href="#Zoltan_Free_Params">Zoltan_Free_Params</a></b>: Frees a parameter
list.</blockquote>
See also:&nbsp; <a href="dev_add_params.html">Adding new parameters in
Zoltan</a>.
<p>

<!------------------------------------------------------------------------->
<hr>
<a NAME="Zoltan_Set_Param"></a>
<hr>
int <b>Zoltan_Set_Param</b>(struct <b><a href="dev_lb_structs.html">Zoltan_Struct</a></b>
*<i>zz</i>, char *<i>param_name</i>, char *<i>new_val</i>);
<br>
<hr>
<p>The <b>Zoltan_Set_Param</b> function is the <a href="../ug_html/ug_interface_init.html#Zoltan_Set_Param">user
interface for parameter setting</a>. Its principle purpose is to call a
sequence of more domain-specific routines for setting domain-specific parameters
(e.g., <b>Zoltan_RCB_Set_Param</b>). If you are adding algorithms to Zoltan,
you must write one of these domain-specific parameter routines and modify
<b>Zoltan_Set_Param</b>
to call it. <b>Zoltan_RCB_Set_Param</b> can serve as a template for this task.
The arguments to this routine are two strings <i>param_name</i> and <i>new_val</i>.
The domain-specific routines return an integer value with the following
meaning.
<blockquote>0 - The parameter name was found, and the value passed all
error checks.
<br>1 - The parameter name was not found among the parameters known by
the domain-specific routine.
<br>2 - The parameter name was found, but the value failed the error checking.
<br>3 - Same as 0, but do not add parameter and value to linked list.
<br>Other - More serious error; value is an <a href="../ug_html/ug_interface.html#Error Codes">error
code</a>.</blockquote>
If one of the domain-specific parameter routines returns with a 0,
<b>Zoltan_Set_Param</b>
adds the parameter and the value (both strings) to a linked list of such
pairs that is pointed to by the <i>Params</i> field of the <i>zz</i> structure.
<table WIDTH="100%" >
<tr VALIGN=TOP>
<td VALIGN=TOP WIDTH="20%"><b>Arguments:</b></td>

<td WIDTH="80%"></td>
</tr>

<tr>
<td VALIGN=TOP>&nbsp;&nbsp; <i>zz</i></td>

<td>The Zoltan structure whose parameter value is being modified.</td>
</tr>

<tr>
<td VALIGN=TOP>&nbsp;&nbsp; <i>param_name</i></td>

<td>A string containing the name of the parameter being modified. It is
automatically converted to all upper-case letters.</td>
</tr>

<tr>
<td VALIGN=TOP>&nbsp;&nbsp; <i>new_val</i></td>

<td>The new value desired for the parameter, expressed as a string.</td>
</tr>

<tr>
<td><b>Returned Value:</b></td>

<td></td>
</tr>

<tr>
<td VALIGN=TOP>&nbsp;&nbsp; int</td>

<td><a href="../ug_html/ug_interface.html#Error Codes">Error code</a>.</td>
</tr>
</table>


<!------------------------------------------------------------------------->
<hr>
<a NAME="Zoltan_Set_Param_Vec"></a>
<hr>
int <b>Zoltan_Set_Param_Vec</b>(struct <b><a href="dev_lb_structs.html">Zoltan_Struct</a></b>
*<i>zz</i>, char *<i>param_name</i>, char *<i>new_val</i>, int <i>index</i>);
<br>
<hr>
<p>
This routine works the same way as <a href="#Zoltan_Set_Param">
Zoltan_Set_Param</a>, but is used for vector parameters.
A vector parameter is a parameter that in
addition to a name also has a set of indices, usually starting at 0. Each entry (component) may have a different value. This routine
sets a single entry (component) of a vector parameter. If you want all entries (components) of a vector parameter to have the
same value, set the parameter using <a href="#Zoltan_Set_Param">
Zoltan_Set_Param</a> as if it were a scalar parameter. 

<!------------------------------------------------------------------------->
<hr>
<a NAME="Zoltan_Check_Param"></a>
<hr>
int <b>Zoltan_Check_Param</b>( char *<i>param_name</i>,
char *<i>new_val</i>, <b>PARAM_VARS</b> *<i>params</i>, <b>PARAM_UTYPE
</b>*<i>result</i>,
int *<i>matched_index</i>);
<br>
<hr>The <b>Zoltan_Check_Param</b> routine simplifies the task of writing your
own domain-specific parameter setting function. <b>Zoltan_Check_Param</b> compares
the <i>param_name</i> string against a list of strings that you provide,
and if a match is found it extracts the new value from the <i>new_val</i>
string. See <b>Zoltan_RCB_Set_Param</b> for an example of how to use this routine.
<table WIDTH="100%" >
<tr VALIGN=TOP>
<td VALIGN=TOP WIDTH="20%"><b>Arguments:</b></td>

<td WIDTH="80%"></td>
</tr>

<tr>
<td VALIGN=TOP>&nbsp;&nbsp; <i>param_name</i></td>

<td>A capitalized string containing the name of the parameter being modified.</td>
</tr>

<tr>
<td VALIGN=TOP>&nbsp;&nbsp; <i>new_val</i></td>

<td>The new value desired for the parameter, expressed as a string.</td>
</tr>

<tr>
<td VALIGN=TOP>&nbsp;&nbsp; <i>params</i></td>

<td>The data structure (defined in <i>params/params_const.h</i>) describing
the domain-specific parameters to be matched against. The data structure
is an array of items, each of which consists of four fields. The first
field is a string that is a capitalized name of a parameter. The second
field is an address that is unused in
<b>Zoltan_Check_Param</b>, but is used
in <b><a href="#Zoltan_Assign_Param_Vals">Zoltan_Assign_Param_Vals</a></b>. The
third field is another capitalized string that indicates the type of the
parameter from the first field. Currently supported types are "INT", "INTEGER",
"FLOAT", "REAL", "DOUBLE", "LONG", "STRING" and "CHAR". It is easy to add additional types
by simple modifications to <b>Zoltan_Check_Param</b> and <b><a href="#Zoltan_Assign_Param_Vals">Zoltan_Assign_Param_Vals</a></b>.
The fourth field is an integer that gives the dimension (length) of
the parameter, if it is a vector parameter. Scalar parameters have dimension 0.
The array is terminated by an item consisting of four NULL fields. See
<b>Zoltan_RCB_Set_Param</b>
for an example of how to set up this data structure.&nbsp;</td>
</tr>

<tr>
<td VALIGN=TOP>&nbsp;&nbsp; <i>result</i></td>

<td>Structure of information returned by <b>Zoltan_Check_Param</b> (defined
in <i>params/params_const.h</i>).&nbsp; If <i>param_name</i> matches any
of the parameter names from the first field of the <i>params</i> data structure,

<b>Zoltan_Check_Param</b> attempts to decode the value in <i>new_val</i>.
The type of the value is determined by the third field in the <i>params</i>
data structure. If the value decodes properly, it is returned in <i>result</i>.&nbsp;</td>
</tr>

<tr>
<td VALIGN=TOP>&nbsp;&nbsp; <i>matched_index</i></td>

<td>If <i>param_name</i> matches, then <i>matched_index</i> returns the
index into the <i>params</i> array that corresponds to the matched parameter
name. The <i>matched_index</i> and <i>result</i> values allow the developer
to check that values being assigned to parameters are valid.&nbsp;</td>
</tr>

<tr>
<td><b>Returned Value:</b></td>

<td></td>
</tr>

<tr>
<td VALIGN=TOP>&nbsp;&nbsp; int</td>

<td>0 - <i>param_name</i> found in <i>params</i> data structure and <i>new_val</i>
decodes OK.&nbsp;
<br>1 - <i>param_name</i> not found in <i>params</i> data structure.&nbsp;
<br>2 - <i>param_name</i> found in <i>params</i> data structure but <i>new_val</i>
doesn't decode properly.&nbsp;</td>
</tr>
</table>


<!------------------------------------------------------------------------->
<hr>
<a NAME="Zoltan_Bind_Param"></a>
<hr WIDTH="100%">
int <b>Zoltan_Bind_Param </b>(<b>PARAM_VARS</b>
*<i>params,</i> char *<i>name,</i> void *<i>var</i>);
<br>
<hr WIDTH="100%">
<br>This routine is used to associate the name of a parameter in the parameter
array <i>params</i> with a variable pointed to by <i>var</i>.
<br>Note that since the variable to be bound can be of an arbitrary type,
the pointer should be cast to a void pointer. <b>Zoltan_Bind_Param</b> must
be called before <b><a href="#Zoltan_Assign_Param_Vals">Zoltan_Assign_Param_Vals</a></b>,
where the actual assignment of values takes place.
<table WIDTH="100%" NOSAVE >
<tr VALIGN=TOP>
<td VALIGN=TOP WIDTH="20%"><b>Arguments:</b></td>

<td WIDTH="80%"></td>
</tr>

<tr>
<td VALIGN=TOP>&nbsp;&nbsp; <i>params</i></td>

<td>The data structure describing the domain-specific parameters to be
matched against. The data structure is an array of items, each of which
consists of four fields. The first field is a string that is a capitalized
name of a parameter. The second field is an address that is unused in
<b><a href="#Zoltan_Check_Param">Zoltan_Check_Param</a></b>,
but is used in <b><a href="#Zoltan_Assign_Param_Vals">Zoltan_Assign_Param_Vals</a></b>.
The third field is another capitalized string that indicates the type
of the parameter from the first field. Currently supported types are "INT",
"INTEGER", "FLOAT", "REAL", "DOUBLE", "LONG", "STRING" and "CHAR". 
It is easy to add additional types by simple modifications to <b><a href="#Zoltan_Check_Param">Zoltan_Check_Param</a></b>
and <b><a href="#Zoltan_Assign_Param_Vals">Zoltan_Assign_Param_Vals</a></b>. 
The fourth field is an integer that gives the dimension (length) of
the parameter, if it is a vector parameter. Scalar parameters have dimension 0.
The array is terminated by an item consisting of four NULL fields.</td>
</tr>

<tr>
<td>&nbsp;&nbsp; <i>name</i></td>

<td>A capitalized string containing the name of the parameter being modified.</td>
</tr>

<tr VALIGN=TOP NOSAVE>
<td>&nbsp;&nbsp; <i>var</i></td>

<td NOSAVE>A pointer to the variable&nbsp; you wish to associate with the
parameter name <i>name.</i>&nbsp; The pointer should be type cast to a
void pointer. The user is responsible for ensuring that the pointer really
points to a variable of appropriate type.&nbsp; A NULL pointer may be used
to "unbind" a variable such that it will not be assigned a value upon future
calls to <b><a href="#Zoltan_Assign_Param_Vals">Zoltan_Assign_Param_Vals</a>.</b></td>
</tr>

<tr>
<td><b>Returned Value:</b></td>

<td></td>
</tr>

<tr VALIGN=TOP NOSAVE>
<td>&nbsp;&nbsp; int</td>

<td NOSAVE><a href="../ug_html/ug_interface.html#Error Codes">Error code</a>.</td>
</tr>
</table>

<p>


<!------------------------------------------------------------------------->
<hr>
<a NAME="Zoltan_Bind_Param_Vec"></a>
<hr WIDTH="100%">
int <b>Zoltan_Bind_Param_Vec</b>(<b>PARAM_VARS</b>
*<i>params,</i> char *<i>name,</i> void *<i>var</i>, int <i>dim</i>);
<br>
<hr WIDTH="100%">
<p>
Same as Zoltan_Bind_Param, but for vector parameters. The additional
parameter <i>dim</i> gives the dimension or length of the vector parameter.
</p>

<!------------------------------------------------------------------------->
<hr>
<a NAME="Zoltan_Assign_Param_Vals"></a>
<hr>
int <b>Zoltan_Assign_Param_Vals</b>(<b>PARAM_LIST</b>
*<i>change_list</i>, <b>PARAM_VARS</b> *<i>params,
</i>int<i> debug_level,</i>
int <i>my_proc,</i> int <i>debug_proc</i>);
<br>
<hr>This routine changes parameter values as specified by the list of names
and new values which is associated with a Zoltan structure. To
use this routine, parameter values should first be set to their defaults,
and then
<b>Zoltan_Assign_Param_Vals</b> should be called to alter the values
as appropriate. See <b>Zoltan_RCB</b> for a template.
<table WIDTH="100%" >
<tr VALIGN=TOP>
<td VALIGN=TOP WIDTH="20%"><b>Arguments:</b></td>

<td WIDTH="80%"></td>
</tr>

<tr>
<td VALIGN=TOP>&nbsp;&nbsp; <i>change_list</i></td>

<td>The linked list of parameter names and values which is constructed
by <b><a href="#Zoltan_Set_Param">Zoltan_Set_Param</a></b> and is a field of an
<b><a href="dev_lb_structs.html#Zoltan_Struct">Zoltan_Struct</a></b>
data structure (defined in <i>params/param_const.h</i>).&nbsp;</td>
</tr>

<tr>
<td VALIGN=TOP>&nbsp;&nbsp; <i>params</i></td>

<td>The data structure (defined in <i>params/params_const.h</i>) describing
the domain-specific parameters to be matched against. The data structure
is an array of items, each of which consists of three fields. The first
field is a string which is a capitalized name of a parameter. The second
field is an address of the parameter which should be altered. The third
field is another capitalized string which indicates the type of the parameter
being altered. Currently supported types are "INT", "INTEGER", "FLOAT", "REAL", "DOUBLE",
"LONG", "STRING" and "CHAR". It is easy to add additional types by simple
modifications to <b><a href="#Zoltan_Check_Param">Zoltan_Check_Param</a></b> and
<b>Zoltan_Assign_Param_Vals</b>.
The array is terminated by an item consisting of three NULL fields.&nbsp;</td>
</tr>

<tr>
<td>&nbsp;&nbsp; <i>debug_level</i></td>

<td>Zoltan debug level. (Normally this is <i>zz->Debug_Level</i>.)</td>
</tr>

<tr>
<td>&nbsp;&nbsp; <i>my_proc</i></td>

<td>Processor number. (Normally this is<i> zz->Proc</i>.)</td>
</tr>

<tr>
<td>&nbsp;&nbsp; <i>debug_proc</i></td>

<td>Processor number for debugging. (Normally this is <i>zz->Debug_Proc</i>.)</td>
</tr>

<tr>
<td></td>

<td></td>
</tr>

<tr>
<td><b>Returned Value:</b></td>
</tr>

<tr>
<td>&nbsp;&nbsp;&nbsp; int</td>

<td><a href="../ug_html/ug_interface.html#Error Codes">Error code</a>.</td>
</tr>

<tr>
<td></td>

<td></td>
</tr>
</table>
The last three input parameters may seem strange. They are present to support
Zoltan's debugging features. If the parameter utility code is used outside
of Zoltan, these&nbsp; parameters may be removed or simply set these input
values to zero in the function call.
<p>

<!------------------------------------------------------------------------->
<hr WIDTH="100%">
<a NAME="Zoltan_Free_Params"></a>
<hr>
void <b>Zoltan_Free_Params </b>(<b>PARAM_LIST</b>
**<i>param_list</i> );
<hr WIDTH="100%">
<br>This routine frees the parameters in the list pointed to by <i>param_list</i>.
<br>&nbsp;
<table WIDTH="100%" >
<tr VALIGN=TOP>
<td VALIGN=TOP WIDTH="20%"><b>Arguments:</b></td>

<td WIDTH="80%"></td>
</tr>

<tr>
<td VALIGN=TOP>&nbsp;&nbsp; <i>param_list</i></td>

<td>A pointer to a list (array) of parameters to be freed.&nbsp; <b>PARAM_LIST</b>
is defined in <i>params/param_const.h</i>.</td>
</tr>
</table>

<p>

<!------------------------------------------------------------------------->
<hr WIDTH="100%">
<br>[<a href="dev.html">Table of Contents</a>&nbsp; |&nbsp; <a href="dev_services_parallel.html">Next:&nbsp;
Parallel Computing Routines</a>&nbsp; |&nbsp; <a href="dev_services.html">Previous:&nbsp;
Services</a>&nbsp; |&nbsp; <a href="https://www.sandia.gov/general/privacy-security/index.html">Privacy and Security</a>]
</body>
</html>
